Release 10.1A: OpenEdge Development:
ProDataSets

Creating Data-Relation objects

The Data-Relation object only exists with respect to a ProDataSet. Therefore, a dynamic Data-Relation is created by executing a ProDataSet object method, not with a CREATE statement for a separate object. You cannot delete a Data-Relation. When the ProDataSet object is deleted or cleared, its Data-Relation objects are automatically deleted.

Use the ADD-RELATION method to add a relation to a dynamic ProDataSet:

Syntax

relation-handle = dataset-handle:ADD-RELATION ( parent-buffer-handle, child-buffer-handle, [ field-mapping-list ] [,reposition-mode ] ) .

In the ADD-RELATION method:

parent-buffer-handle is the buffer-handle (or optionally the temp-table handle) of the Data-Relation parent.
child-buffer-handle is the buffer-handle or temp-table-handle of the Data-Relation child.
field-mapping-list is an expression that evaluates to a comma-delimited list of parent-field, child-field pairs to describe the relation between parent and child, using the same form as the Data-Relation phrase in a static DEFINE DATASET statement: parent-field1,child-field1[,parent-field2,child-field2]… Make sure that the list does not contain any embedded spaces. Progress does not trim the elements in the list.
reposition-mode is a logical value. If true, it makes the Data-Relation a reposition relation; if it is false, the Data-Relation is a selection relation, which is the default.

You can add multiple Data-Relations involving the same parent member temp-table. A table can be a child in only one relation.

If the buffer handles specified are not in the ProDataSet, or fields supplied are not in the indicated tables, Progress raises an error at run time.

The ADD-RELATION method returns a handle to the Data-Relation object, or the Unknown value (?) if there was an error.

A buffer for a temp-table does not have to have any Data-Relations at all. In this case, it is treated as an independent top-level data table within the ProDataSet. It must therefore be filled independently, either individually or when the ProDataSet as a whole is filled. There can be any number of top-level data tables (tables that are not the child in a Data-Relation). Each top-level table can have child tables or not.

You cannot take a static ProDataSet and add a buffer to it using the ADD-BUFFER method, or replace its buffers using SET-BUFFERS, or erase its buffer definition using the CLEAR method. However, you can add a dynamic Data-Relation to a static ProDataSet. This could be useful in the case where you need to use relations to navigate the ProDataSet but which are not necessary for filling it. Another case could be where a single ProDataSet might require different relations, depending on how it is used.

A difference in the ProDataSet’s relations does not cause an error when the ProDataSet is passed as a parameter. If the ProDataSet is received dynamically using the DATASET-HANDLE form, then Progress creates all the Data-Relations that are defined in the caller as dynamic relations in the ProDataSet in the called procedure.

If the ProDataSet is received statically using the DATASET parameter form, then Progress ignores the relations in the caller and uses the Data-Relation definitions in the receiving procedure’s static ProDataSet definition. This means, for example, that you could pass a static ProDataSet from server to client, add a Data-Relation to it dynamically on the client, and then pass the ProDataSet back to the server without error. If the server-side definition is static, the extra relation on the client is simply ignored when it arrives on the server.